<!DOCTYPE html>
<HTML lang="en">
<HEAD>
    <title> The Baby X Resource Compiler </title>
    <meta charset="UTF-8">
<style>
body {
    margin-left: 120px;
    background-color: #C0C0FF;
}

P {
    width: 50em;
}

pre{
    width : 50em;
    background-color: #FFFFFF;
}
    .nav {
    width:10em;
    }
    .cell{
        width:38em;
    }
    .xcell{
        all: initial; /* Set default CSS */
    }
    
    #navlist
    {
        vertical-align:top;
    }
    #navlist li {
        margin:0
    }
    
    /* Add a black background color to the top navigation */
    .topnav {
      background-color: #c0c0ff;
      overflow: hidden;
    }

    /* Style the links inside the navigation bar */
    .topnav a {
      float: left;
      color: #c0c0ff;
      text-align: center;
      padding: 14px 4px;
      text-decoration: none;
      font-size: 17px;
    }

    /* Change the color of links on hover */
    .topnav a:hover {
      background-color: #d0d0ff;
      color: black;
    }

    /* Add a color to the active/current link */
    .topnav a.active {
      background-color: #04AA6D;
      color: white;
    }
    
    .center {
      display: block;
      margin-left: auto;
      margin-right: auto;
      width: 50%;
    }
</style>

</HEAD>
<BODY>
    <div class="topnav">
        <A href="https://github.com/MalcolmMcLean"><IMG src="BabyXLogos/Cartoon_Owl_clip_art.svg" alt="Cartoon Owl" height="32"></A>
        <A href="https://github.com/MalcolmMcLean/babyxrc"><IMG src="BabyXLogos/baby-x-rc-logo.svg" alt="BabyXRC logo" height="32"></A>
        <A href="https://malcolmmclean.github.io/babyx"><IMG src="BabyXLogos/babyx-banner.svg" alt="BabyX banner" height="32"></A>
        <A href="https://github.com/MalcolmMcLean/babyxrc"><IMG src="BabyXLogos/babyxrc-banner.svg" alt="BabyXRC banner" height="32"></A>
        <A href="BabyXFS.html"><IMG src="BabyXLogos/babyxfs-banner.svg" alt="BabyXFS banner" height="32"></A>
        <A href="https://github.com/MalcolmMcLean/minixml"><IMG src="BabyXLogos/MiniXML_logo.png" alt="MiniXML logo" height="32"></A>
        <A href="https://malcolmmclean.github.io/minibasic"><IMG src="BabyXLogos/MiniBasicLogo.svg" alt = "MiniBasic logo" height="32"></A>
        <A href="https://malcolmmclean.github.io/binaryimagelibrary"><div style="background-color:white"><IMG src="BabyXLogos/binary-library-logo.svg" alt = "Binary Image library logo" height="32"></div></A>
    </div>
<BR>
<IMG src = "BabyXLogos/babyxrc-title.svg" alt="BabyXRC title" height="50" class="center">
<TABLE>
    <TR>
        <TD class="nav" style="background-color:white;text-align:left;vertical-align:0">
        <BR>
        <ul id="navlist" style="list-style-type:none;margin:0">
         <LI><A href="BBX_FileSystemObject.html">BBX_FileSystemObject</A></LI>
         <LI><A href="BBX_OptionsObject.html">BBX_OptionsObject</A></LI>
         <LI><A href="BabyX_hello.html">BabyX_hello</A></LI>
         <LI><A href="BabyXFS.html">BabyXFS</A></LI>
         <LI><A href="FileSystemXML.html">FileSystemXML</A></LI>
         <II><a href="babyjokes.html">babyjokes</A></LI>
         <LI><A href="babyxfs_shell.html">babyxfs_shell.html</A></LI>
         <LI><A href="bbx_filesystem.html">bbx_filesystem</A></LI>
         <LI><A href="importingdirectories.html">importingdirectories</A></LI>
         <LI><A href="index.html">index</A></LI>
         <LI><A href="sourcefiles.html">sourcefiles</A></LI>
         <LI><A href="usingcsv.html">usingcsv</A></LI>
         <LI><A href="usingloadimage.html">usingloadimage</A></LI>
         <LI><A href="usingoptions.html">usingoptions</A></LI>
         <LI><A href="usingrbtree.html">usingrbtree</A></LI>
         <LI><A href="usingutf8.html">usingutf8</A></LI>
         <LI><A href="usingxmlparser.html">usingxmlparser</A></LI>
       </ul>
            <!-- </nav>  -->
        </TD>
        <TD>
            <P style="width:2em">
            </P>
        </TD>
<TD>
<div style="width:38em">
    <TABLE>
        <TR>
            <TD>
                <BR>
            </TD>
            <TD>
        <div style="float:left;width:20em">
            <BR>
The <A href="https://github.com/MalcolmMcLean/babyxrc">Baby X resource compiler</A> takes binary resources - images, fonts, audio
clips and text - and converts them to compileable C source. Unike most 
other resource compilers, it doesn't simply package binary data, it reads 
in the resource file and converts into data in a form ready to use in 
your program. So images might be provided in any one of a range of image 
formats. However most programs want images as RGBA data. So the Baby X 
resource compiler loads the image, decompresses it, and writes out as 
RGBA. If the input image is the wrong size, the Baby X resource compiler 
will resize it for you.
    </div>
        </TD>
            <TD>
                <div style="width:18em">
                    <div style="width:8em;float:right;top:2px;background-color:white">
            <IMG src="BabyXLogos/baby-x-rc-logo.svg" alt="BabyXRC logo" width="120" height="120">
                </div>
                </div>
        </TD>
        </TR>
        </TABLE>

<P class="cell">
The resource compiler is designed for the world of <A href="BabyX_hello.html">Baby X</A>, the system for writing small or baby programs which have minimal dependencies and will run anywhere. Baby X is meant to meet the needs of the hobby programmer, but is free to anyone for any use. And the resource compiler, babyxrc, is an independent program that can be used by people who don't want it for Baby X.
</P>
 
 <P class="cell">
 We now have an anciliary project, <A href = "http://malcolmmclean.github.io/babyxrc/BabyXFS.html"> BabyXFS </A>, or the Baby X filesystem project. This is designed to allow Baby X programmers to mount directories and embed them in programs. The files use the <A href = "FileSystemXML.html">&lt;FileSystem&gt;</A> XML file format. This allows directories to be packaged up and then imported via the Baby X resource compiler. There is now a suite of babyxfs_ programs to manipulate the FileSystem XML files. A particularly intetesting use case is allowing a program to print out its own source so it can be recompiled on a diferent platform. This is explained as part of the BabyXFS project,&nbsp;<A href="https://github.com/MalcolmMcLean/babyxrc/tree/master/Examples/BabyXFS/writing_own_source">here</A>.
 </P>
<P class ="cell">
The Baby X resource compiler will load most images in most common formats, 
including .jpeg, .png, .tiff, .gif, and .bmp. SVG images are rasterized 
(import SVG  as text data if you want to treat SVG as vector). So the 
<A href="usingloadimage.html">loadimage</A> function will load almost anything,
and you are welcome to steal it for your own projects. (If you enhance or bug fix,
please contact me).
 </P>
<P class="cell">
Audio is loaded as .wav, .aiff, or .mp3. AIFF files with bitrates other 
than 16 bits per sample are not supported, nor are compressed AIFC files, 
with the exception of the special case of AIFC files which reverse 
endianness. MP3 files will be decompressed (include as &lt;binary&gt; if 
you have facilites for playing MP3. There&apos;s a samplerate parameter so you
can include audio from any source and store it at the samplerate required 
by your platform.
</P>
<P class="cell">
The Baby X resource compiler will also take in text in most common formats,
and save it as human-readable ASCII strings, UTF-8, or UTF-16. Text files 
commonly have non-standard extensions, so the format has to be determined 
by heuristic analysis. For this reason it is recommended to use UTF-8 
whereever posible. It&apos;s also recommended to use UTF-8 in the output.
However UTF-16 output is provided for compatibility. By default, surrogate 
pairs are turned off, because the usual reason for using UTF-16 is that 
the program doesn&apos;t want to handle non-fixed width representations.
However you can turn them on with the &quot;allowsurrogatepairs&quot; attribute. You
can incorporate UTF-8 in your source with the &lt;string&gt; tag, but some 
compilers and editors won&apos;t accept it. So the &lt;utf8&gt; tag dumps UTF-8
as ASCII-encoded binary. 
 </P>
 
<P class = "cell">
Users of the Baby X resource compiler will be C programmers, so it is the 
work of a moment to modify the program slightly to output data in a 
slightly different format, for example if you need an exact binary 
signature for audio samples, or if you want images as ARGB rather than 
RGBA. It&apos;s hard to predict these requirements by providing runtime
options. So whilst it sounds a bit 1970s, modifying the program source is 
the best approach.
 </P>
 <P class  = "cell">
 For a developer-oriented documentation of the Baby X resource compiler source,
 see the <A href="sourcefiles.html"> Baby X resource compiler source overview</A>.
 </P>
 </div>
 </TD>
 </TR>
 </TABLE>
<H2>Using the Baby X resource compiler</H2>
<H3>Usage</H3>
<pre>
babyxrc script.xml &gt; outputfile.c

babyxrc -header script.xml &gt; outputfile.h
</pre>
<P>
There is currently only one option, which is to write a header file rather 
an a .c source file.  The Baby X resource  compiler will read in the 
resource list from the script, and write the .c  output file to standard 
output. Errors are passed to stderr, so they will be lost in the output 
unless you redirect it. 
</P>

<H3>Installation</H3>
<P>
The Baby X resource compiler is provided as source. It's all 100% portable 
ANSI C with no dependencies other than those provided in the distribution 
itself and the C standard library. So it should compile with the minimum of 
problems. There's a CMake script to help out, but it's not necessary to
use it. You'll have to put the executable on your path using the operating 
system's specific facilities (usually by adding it to the ${PATH} 
environment variable). It should run on absolutely any machine with a C 
compiler and a standard output. 
 </P>

<H3> Baby X resource compiler script </H3>
<P>
The Baby X resource compiler accepts a simple XML script as input. 
Essentially it is a list of your resource files together with a few 
attributes to control the format you want them output in. So everything is 
together.
 </P>
<pre>
&lt;BabyXRC&gt;
    &lt;string name = "hello"&gt;Hello Baby X&lt;/string&gt;
    &lt;image name = "babyxpic", src = "Babyx.jpeg", width = "100", height = 100"&gt;
    &lt;/image&gt;
    &lt;audio name = "babyxcry", src = "crying.mp3", samplerate = 22050&gt;
    &lt;/audio&gt;
&lt;/BabyXRC&gt;
</pre>
<P>
Here's a very simple sample Baby X resource compiler script file 
containing on string, one image, and one audio clip. If the image is not 
100x100 it will be resized, and the MP3 will be decompressed and resampled 
at 22050Hz. 
</P>
<H3>Tag list</H3>
<P>
<UL>
<LI> &lt;string&gt; - output data as a human-readable C string </LI>
<LI> &lt;utf8&gt; - output data as UTF-8 </LI>
<LI> &lt;utf16&gt; - output data as UTF-16 </LI>
<LI> &lt;comment&gt; - add comment to output file </LI>
<LI> &lt;binary&gt; - dump raw binary data unprocessed </LI> 
<LI> &lt;image&gt; - output data as a 32 bit rgba buffer </LI> 
<LI> &lt;font&gt; - rip a font, rasterise, and output data as greyscale 
glyphs 
</LI>
<LI> &lt;audio&gt; - output dat as 16-bit pcm samples </LI>
<LI> &lt;cursor&gt; - output data as a 32 rgba image with hotspot </LI>
<LI> &lt;dataframe&gt; - read data from a CSV file and output as array of 
C structs </LI> 
<LI> &lt;international&gt; child &lt;string&gt; and &lt;utf8&gt; tags 
represent translations 
</LI>
</UL>
<P>
The tag type gives the output format, not the input format of the 
resource. Usually the resource compiler will determine the format of
the resource from its extension or, in the case of text files, by
using a heuristic.
</P>
<P>
Tags take attributes. All tags can take a &quot;name&quot; attribute, 
which gives the base name of the C identifiers output. &quot;name&quot; is 
usually optional
as the name can be generated from the resource file name. All tags also 
take a "src" attribute which gives the path to the resource file. Text
tags &lt;string&gt; &lt;utf8&gt; &lt;utf16&gt; can omit the 
&quot;src&quot; attribute if text is included in within the tags.  
</P>

<H3> &lt;string&gt; tag </H3>
<P>
<B>Attributes</B> name, src, const
</P>

<pre>
&lt;string name = "fred"&gt;Fred Bloggs&lt;/string&gt;
&lt;string name = "fred" const="true"&gt;"My name is \"Fred Bloggs\"\n"&lt;/string&gt;
&lt;string name = "fred", src = "fred.txt"&gt;&lt;/string&gt;
</pre>
<P>
In the first case we are creating a string with the value "Fred Bloggs".
<BR>
In the second case the string is quoted, so it is not escaped but is
output as is. (This is useful for entering printf format strings).
And it is also const.In the third case, the string is read from an external
file. It will be escaped so tabs will be expanded to "\t" and newlines to "\n". 
</P>

<H3> &lt;utf8&gt; tag </H3>
<P>
<B>Attributes</B> name, src
</P>
<pre>
&lt;utf8 name = "fred"&gt;Fred Bloggs/n&gt;&lt;/utf8&gt;
&lt;utf8 name = "fred" src = "fredunicode"&gt;&lt;/utf8&gt;
</pre>
<P>
In the first case we are creating UTF-8 string with the value "Fred 
Bloggs". You can put UTF-8 in this position to etner human-readable
extended character (this text file is ASCII so we can't show that).
<BR>
In the second case we are creating a UTF-8 string from an input file.
The resource compiler will attempt to dtermine the format. However it
is recommedend to use UTF-8.
</P>

<H3>&lt;utf16&gt; tag</H3>
<P>
<B>Attributes</B> name, src, allowsurrogatepairs
</P>
<pre>
&lt;utf16 name = "fred"&gt;Fred Bloggs&lt;/utf16&gt;
&lt;utf16 src = "fred.utf8"&gt;&lt;/utf16&gt;
&lt;utf16 src = "fred.utf8" allowsurrogatepairs="true"&gt;&lt;/utf16&gt;
</pre>
<P>
In the first case we are creating UTF-16 with the value "Fred Bloggs".
<BR>
In the second case we are creating UTF-16 from a text file. The extension
suggests that it is UTF-8 file (as recommended). The resource compiler 
will re-encode it as UTF-16. name isn't given and will default to 
"fred", based on the file name.
<BR>
In the third case we are allowing surrogate pairs in the UTF-16 output.
By default this isn't on an code points over 0xFFFF will be mapped to 
0xFFFE (unknown character). This is because a lot of code relies on one
wide character representing one code point.
</P>
<H3>&lt;comment&gt; tag</H3>
<P>
<B>Attributes</B> src
</P>

<pre>
&lt;comment&gt;Add this comment to my source&lt;/comment&gt;
&lt;comment src = "licence.txt"&gt;&lt;/comment&gt;
</pre>
<P>
In the first case the comment text is embedded in the script file.
<BR>
In the second case we load in the text from an external file.
</P>

<H3>&lt;binary&gt; tag</H3>
<P>
<B>Attributes</B> name, src
</P>
<pre>
&lt;binary name = Fred, src = "fred.bin"&gt;&lt;/binary&gt;
</pre>
<P>
In the first case the file "fred.bin" is simply read in and passed out
as binary bytes, with no processing.
</P>

<H3>&lt;image&gt; tag</H3>
<P>
<B>Attributes</B> name, src, width, height
</P>
<pre>
&lt;image name = "fred" src = "fred.jpeg"&gt;&lt;/image&gt;
&lt;image name = "fred" src = "fred.tiff", width = "100", height = "80"&gt;&lt;/image&gt;
</pre>
<P>
In the first case the image is read from "fred.jpeg" and written out as
32 bit rgba values.
<BR>
In the second case the image is read from "fred.tiff" and resized to
width 100 pixels, height 80 pixels, then written out as 32 bit rgba 
values.
</P>
<P>
Supported formats are .png, .jpeg, .gif, .bmp, .tiff and .svg. The format
will be determined form the file extension. Svg files will be converted to
raster.
</P>

<H3> &lt;font&gt; tag</H3>
<P>
<B>Attributes</B> name, src, points
</P>
<pre>
&lt;font name = "fred", src = "fredsfont.ttf", points = "12"&gt;&lt;/font&gt;
&lt;font name = "fred", src = "fredsfont.bdf"&gt;&lt;/font&gt;
</pre>
<P>
In the first case we a loading a true type font, and outputting raster
glyphs for 12 point text.
<BR>
In the second case we are loading a BDF raster font which cannot be
resized.
</P>
<P>
The &lt;font&gt; tag is mainly intended for ripping true type fonts and
rasterising them so they can be used by simple programs. If you 
have runtime support for true type fonts, load the font with the &lt;binary&gt;
tag.
</P>

<H3>&lt;audio&gt; tag</H3>
<P>
<B>Attributes</B> name, src, samplerate
</P>

<pre>
&lt;audio name = "fred", src = "fred.wav"&gt;&lt;/audio&gt;
&lt;audio name = "fred", src = "fred.mp3", samplerate = "22050"&gt;&lt;/audio&gt;
</pre>
<P>
In the first case we are inputting "fred,wav" and writing the data out
as 16 bit pcm samples with minimal processing.
<BR>
In the second case we are inputting an MP3 file, decompressing it, 
resampling at 22050Hz, the outputting as PCM samples.
</P>
<P>
If you have facilities for playing MP3 streams, load the MP3 with the
&lt;binary&gt; tag.
</P>
  
<H3>&lt;cursor&gt; tag</H3>
<P>
<B>Attributes</B> name, src
</P>
<pre>
&lt;cursor name = "fred", src = "fred.cur"&gt;&lt;/cursor&gt;
</pre>
<P>
In the first case we are loading a Microsoft .cur file, and outputting it 
as 32 bit rgba buffer plus a hotspot.
</P>

<H3> &lt;dataframe&gt; tag</H3>
<P>
<B>Attributes</B> name, src
</P>
<pre>
&lt;dataframe name = "payroll", src = "employees.csv"&gt;&lt;/dataframe&gt;
</pre>
<P>
We load in a dataframe, which in C is simply an array of structs which 
represent data from an external source. Currently the only format 
supported is csv.
</P> 
<H3>&lt;international&gt; tag</H3>
<P>
<B>Attributes</B> name <BR>
<B>Children</B> &lt;string&gt; &lt;utf8&gt; tags.

<pre>
&lt;international name = "hellofred"&gt;
  &lt;string language = "english"&gt;Hello Fred&lt;/string&gt;
  &lt;string language = "french"&gt;Bonjour Fred&lt;/string&gt;
  &lt;utf8 src = "chinesefred.unicode" language = "chinese"&gt;&lt;/utf8&gt;
&lt;/international&gt;
</pre>
<P>
Here we are setting up an internationalised string with the base identifer 
"hellofred" and English, French, and Chinese translations. The English 
and French are entered directly, the Chinese is read in from an external 
file. In this context, &lt;string&gt; and &lt;utf8&gt; tags should take a "language"
attribute.
</P>
<H3>Helping out</H3>
<P>
The Baby X resource compiler is provided as a service to the C programming 
community. You can help out by enhancing the program, bug fixing, and so 
on. You can also help by promoting it and recommending it to your friends. 
The more users we have, the more developers we will attract, and the 
project should go from strength to strength.
<P>
<P>
On the wishlist is an MP3 encoder to allow users to store resources in 
.wav file format and incorporate them in their programs as MP3. The bmp 
file loader won't support some of the more exotic bitmap formats (run 
length encoding and bit masks). We could also do with a "filesystem" 
tag to allow users to package a directory as a runtime-accessible 
filesystem, stored in the programs data section. We also need more work on 
internationalisation. Functions to mix audio would also be useful.
</P>
<P>
To add a new tag, add it to the list in main. It will likely have the 
attributes "name" and "src". If there are any other attributes with new 
names, add a variable declared as
</P>
<pre>
const char *attributenamestr;
...

attributenamestr = xml_getattribute(node, "attributename");
</pre>
 <P>
 The write a function called processtagnametag which takes a FILE *
as the first parameter, and the attributes as additional parameters.
Note that these will be null if the user doesn't provide the attribute.
 </P>
<P>
To add an attribute, create the variable to hold the string using the
convention above. Then add the attribute to the parameter list of the
tag process function. 
</P>
<P>
If the tag has children or for other reasons is difficult to process using 
the above interface, the  write a "processtagnamenode" function which
takes the node as a parameter. You'll then need to use the xml functions 
in xmlparser.h to access the node's information.
 </P>
 <div style="max-width:fit-content;margin-left:auto;margin-right:auto"><a href='https://www.free-website-hit-counter.com'><img src='https://www.free-website-hit-counter.com/c.php?d=6&id=172126&s=10' alt='Free Website Hit Counter'></a><br><small><a href='https://www.free-website-hit-counter.com' title="Free Website Hit Counter">Free website hit counter</a></small></div>
 </BODY>
 </HTML>
